Propagação de Contexto Assíncrono em JavaScript: Rastreamento de Requisições e Continuação com AsyncLocalStorage

No desenvolvimento JavaScript moderno do lado do servidor, especialmente com Node.js, as operações assíncronas são onipresentes. Gerenciar estado e contexto através dessas fronteiras assíncronas pode ser um desafio. Este artigo explora o conceito de propagação de contexto assíncrono, focando em como usar AsyncLocalStorage para alcançar o rastreamento de requisições e a continuação de forma eficaz. Examinaremos seus benefícios, limitações e aplicações no mundo real, fornecendo exemplos práticos para ilustrar seu uso.

Entendendo a Propagação de Contexto Assíncrono

Propagação de contexto assíncrono refere-se à capacidade de manter e propagar informações de contexto (por exemplo, IDs de requisição, detalhes de autenticação de usuário, IDs de correlação) através de operações assíncronas. Sem uma propagação de contexto adequada, torna-se difícil rastrear requisições, correlacionar logs e diagnosticar problemas de desempenho em sistemas distribuídos.

Abordagens tradicionais para gerenciar o contexto frequentemente dependem da passagem explícita de objetos de contexto através de chamadas de função, o que pode levar a um código verboso e propenso a erros. O AsyncLocalStorage oferece uma solução mais elegante, fornecendo uma maneira de armazenar e recuperar dados de contexto dentro de um único contexto de execução, mesmo através de operações assíncronas.

Apresentando o AsyncLocalStorage

O AsyncLocalStorage é um módulo nativo do Node.js (disponível desde a versão v14.5.0) que fornece uma maneira de armazenar dados que são locais ao ciclo de vida de uma operação assíncrona. Ele essencialmente cria um espaço de armazenamento que é preservado através de chamadas await, promessas e outras fronteiras assíncronas. Isso permite que os desenvolvedores acessem e modifiquem dados de contexto sem passá-los explicitamente.

Principais características do AsyncLocalStorage:

• Propagação Automática de Contexto: Valores armazenados no AsyncLocalStorage são propagados automaticamente através de operações assíncronas dentro do mesmo contexto de execução.
• Código Simplificado: Reduz a necessidade de passar objetos de contexto explicitamente através de chamadas de função.
• Observabilidade Aprimorada: Facilita o rastreamento de requisições e a correlação de logs e métricas.
• Segurança de Thread (Thread-Safety): Fornece acesso seguro a dados de contexto dentro do contexto de execução atual.

Casos de Uso para o AsyncLocalStorage

O AsyncLocalStorage é valioso em vários cenários, incluindo:

• Rastreamento de Requisições: Atribuir um ID único a cada requisição recebida e propagá-lo por todo o ciclo de vida da requisição para fins de rastreamento.
• Autenticação e Autorização: Armazenar detalhes de autenticação do usuário (por exemplo, ID do usuário, papéis, permissões) para acessar recursos protegidos.
• Registro (Logging) e Auditoria: Anexar metadados específicos da requisição a mensagens de log para melhor depuração e auditoria.
• Monitoramento de Desempenho: Rastrear o tempo de execução de diferentes componentes dentro de uma requisição para análise de desempenho.
• Gerenciamento de Transações: Gerenciar o estado transacional através de múltiplas operações assíncronas (por exemplo, transações de banco de dados).

Exemplo Prático: Rastreamento de Requisições com AsyncLocalStorage

Vamos ilustrar como usar o AsyncLocalStorage para rastreamento de requisições em uma aplicação Node.js simples. Criaremos um middleware que atribui um ID único a cada requisição recebida e o torna disponível durante todo o ciclo de vida da requisição.

Exemplo de Código

Primeiro, instale os pacotes necessários (se preciso):

            npm install uuid express
            

              
                Copy
              
            
          

Aqui está o código:

            // app.js
const express = require('express');
const { AsyncLocalStorage } = require('async_hooks');
const { v4: uuidv4 } = require('uuid');

const app = express();
const asyncLocalStorage = new AsyncLocalStorage();
const port = 3000;

// Middleware para atribuir um ID de requisição e armazená-lo no AsyncLocalStorage
app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    next();
  });
});

// Simula uma operação assíncrona
async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      const requestId = asyncLocalStorage.getStore().get('requestId');
      console.log(`[Async] Request ID: ${requestId}`);
      resolve();
    }, 50);
  });
}

// Manipulador de rota (Route handler)
app.get('/', async (req, res) => {
  const requestId = asyncLocalStorage.getStore().get('requestId');
  console.log(`[Route] Request ID: ${requestId}`);
  await doSomethingAsync();
  res.send(`Hello World! Request ID: ${requestId}`);
});

app.listen(port, () => {
  console.log(`Aplicação escutando em http://localhost:${port}`);
});

            

              
                Copy
              
            
          

Neste exemplo:

1. Criamos uma instância de AsyncLocalStorage.
2. Definimos um middleware que atribui um ID único a cada requisição recebida usando a biblioteca uuid.
3. Usamos asyncLocalStorage.run() para executar o manipulador da requisição dentro do contexto do AsyncLocalStorage. Isso garante que quaisquer valores armazenados no AsyncLocalStorage estejam disponíveis durante todo o ciclo de vida da requisição.
4. Dentro do middleware, armazenamos o ID da requisição no AsyncLocalStorage usando asyncLocalStorage.getStore().set('requestId', requestId).
5. Definimos uma função assíncrona doSomethingAsync() que simula uma operação assíncrona e recupera o ID da requisição do AsyncLocalStorage.
6. No manipulador de rota, recuperamos o ID da requisição do AsyncLocalStorage e o incluímos na resposta.

Quando você executa esta aplicação e envia uma requisição para http://localhost:3000, você verá o ID da requisição registrado tanto no manipulador de rota quanto na função assíncrona, demonstrando que o contexto é propagado corretamente.

Explicação

• Instância de AsyncLocalStorage: Criamos uma instância de AsyncLocalStorage que conterá nossos dados de contexto.
• Middleware: O middleware intercepta cada requisição recebida. Ele gera um UUID e então usa asyncLocalStorage.run para executar o resto do pipeline de manipulação da requisição *dentro* do contexto deste armazenamento. Isso é crucial; garante que qualquer coisa a jusante tenha acesso aos dados armazenados.
• asyncLocalStorage.run(new Map(), ...): Este método aceita dois argumentos: um Map novo e vazio (você pode usar outras estruturas de dados se apropriado para seu contexto) e uma função de callback. A função de callback contém o código que deve ser executado dentro do contexto assíncrono. Quaisquer operações assíncronas iniciadas dentro deste callback herdarão automaticamente os dados armazenados no Map.
• asyncLocalStorage.getStore(): Retorna o Map que foi passado para asyncLocalStorage.run. Nós o usamos para armazenar e recuperar o ID da requisição. Se run não foi chamado, ele retornará undefined, e é por isso que é importante chamar run dentro do middleware.
• Função Assíncrona: A função doSomethingAsync simula uma operação assíncrona. Crucialmente, mesmo sendo assíncrona (usando setTimeout), ela ainda tem acesso ao ID da requisição porque está sendo executada dentro do contexto estabelecido por asyncLocalStorage.run.

Uso Avançado: Combinando com Bibliotecas de Logging

A integração do AsyncLocalStorage com bibliotecas de logging (como Winston ou Pino) pode melhorar significativamente a observabilidade de suas aplicações. Ao injetar dados de contexto (por exemplo, ID da requisição, ID do usuário) nas mensagens de log, você pode facilmente correlacionar logs e rastrear requisições através de diferentes componentes.

Exemplo com Winston

            // logger.js
const winston = require('winston');
const { AsyncLocalStorage } = require('async_hooks');

const asyncLocalStorage = new AsyncLocalStorage();

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.printf(({ timestamp, level, message }) => {
      const requestId = asyncLocalStorage.getStore() ? asyncLocalStorage.getStore().get('requestId') : 'N/A';
      return `${timestamp} [${level}] [${requestId}] ${message}`;
    })
  ),
  transports: [
    new winston.transports.Console()
  ]
});

module.exports = {
  logger,
  asyncLocalStorage
};

            

              
                Copy
              
            
          

            // app.js (modificado)
const express = require('express');
const { v4: uuidv4 } = require('uuid');
const { logger, asyncLocalStorage } = require('./logger');

const app = express();
const port = 3000;

app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    logger.info(`Requisição recebida: ${req.url}`); // Registra a requisição recebida
    next();
  });
});

async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      logger.info('Fazendo algo assíncrono...');
      resolve();
    }, 50);
  });
}

app.get('/', async (req, res) => {
  logger.info('Manipulando a requisição...');
  await doSomethingAsync();
  res.send('Hello World!');
});

app.listen(port, () => {
  logger.info(`Aplicação escutando em http://localhost:${port}`);
});

            

              
                Copy
              
            
          

Neste exemplo:

• Criamos uma instância do logger Winston e a configuramos para incluir o ID da requisição do AsyncLocalStorage em cada mensagem de log. A parte chave é o winston.format.printf, que recupera o ID da requisição (se disponível) do AsyncLocalStorage. Verificamos se asyncLocalStorage.getStore() existe para evitar erros ao registrar logs fora de um contexto de requisição.
• Atualizamos o middleware para registrar a URL da requisição recebida.
• Atualizamos o manipulador de rota e a função assíncrona para registrar mensagens usando o logger configurado.

Agora, todas as mensagens de log incluirão o ID da requisição, facilitando o rastreamento de requisições e a correlação de logs.

Abordagens Alternativas: cls-hooked e Async Hooks

Antes do AsyncLocalStorage se tornar disponível, bibliotecas como cls-hooked eram comumente usadas para a propagação de contexto assíncrono. O cls-hooked usa Async Hooks (uma API de nível mais baixo do Node.js) para alcançar uma funcionalidade semelhante. Embora o cls-hooked ainda seja amplamente utilizado, o AsyncLocalStorage é geralmente preferido devido à sua natureza nativa e desempenho aprimorado.

Async Hooks (async_hooks)

Os Async Hooks fornecem uma API de nível mais baixo para rastrear o ciclo de vida de operações assíncronas. Embora o AsyncLocalStorage seja construído sobre os Async Hooks, usá-los diretamente é muitas vezes mais complexo e menos performático. Os Async Hooks são mais apropriados para casos de uso muito específicos e avançados, onde um controle refinado sobre o ciclo de vida assíncrono é necessário. Evite usar os Async Hooks diretamente, a menos que seja absolutamente necessário.

Por que preferir AsyncLocalStorage em vez de cls-hooked?

• Nativo (Built-in): O AsyncLocalStorage faz parte do núcleo do Node.js, eliminando a necessidade de dependências externas.
• Desempenho: O AsyncLocalStorage é geralmente mais performático que o cls-hooked devido à sua implementação otimizada.
• Manutenção: Como um módulo nativo, o AsyncLocalStorage é mantido ativamente pela equipe principal do Node.js.

Considerações e Limitações

Embora o AsyncLocalStorage seja uma ferramenta poderosa, é importante estar ciente de suas limitações:

• Fronteiras de Contexto: O AsyncLocalStorage só propaga o contexto dentro do mesmo contexto de execução. Se você estiver passando dados entre processos ou servidores diferentes (por exemplo, via filas de mensagens ou gRPC), você ainda precisará serializar e desserializar explicitamente os dados de contexto.
• Vazamentos de Memória (Memory Leaks): O uso inadequado do AsyncLocalStorage pode potencialmente levar a vazamentos de memória se os dados de contexto não forem limpos corretamente. Certifique-se de usar asyncLocalStorage.run() corretamente e evite armazenar grandes quantidades de dados no AsyncLocalStorage.
• Complexidade: Embora o AsyncLocalStorage simplifique a propagação de contexto, ele também pode adicionar complexidade ao seu código se não for usado com cuidado. Garanta que sua equipe entenda como ele funciona e siga as melhores práticas.
• Não é um Substituto para Variáveis Globais: O AsyncLocalStorage *não* é um substituto para variáveis globais. Ele foi projetado especificamente para propagar o contexto dentro de uma única requisição ou transação. O uso excessivo pode levar a um código fortemente acoplado e dificultar os testes.

Melhores Práticas para Usar o AsyncLocalStorage

Para usar o AsyncLocalStorage de forma eficaz, considere as seguintes melhores práticas:

• Use Middleware: Use middleware para inicializar o AsyncLocalStorage e armazenar dados de contexto no início de cada requisição.
• Armazene Dados Mínimos: Armazene apenas dados de contexto essenciais no AsyncLocalStorage para minimizar a sobrecarga de memória. Evite armazenar objetos grandes ou informações sensíveis.
• Evite Acesso Direto: Encapsule o acesso ao AsyncLocalStorage por trás de APIs bem definidas para evitar acoplamento forte e melhorar a manutenibilidade do código. Crie funções auxiliares ou classes para gerenciar os dados de contexto.
• Considere o Tratamento de Erros: Implemente o tratamento de erros para lidar graciosamente com casos em que o AsyncLocalStorage não é inicializado corretamente.
• Teste Exaustivamente: Escreva testes de unidade e de integração para garantir que a propagação de contexto esteja funcionando como esperado.
• Documente o Uso: Documente claramente como o AsyncLocalStorage está sendo usado em sua aplicação para ajudar outros desenvolvedores a entenderem o mecanismo de propagação de contexto.

Integração com OpenTelemetry

OpenTelemetry é um framework de observabilidade de código aberto que fornece APIs, SDKs e ferramentas para coletar e exportar dados de telemetria (por exemplo, rastreamentos, métricas, logs). O AsyncLocalStorage pode ser integrado de forma transparente com o OpenTelemetry para propagar automaticamente o contexto de rastreamento através de operações assíncronas.

O OpenTelemetry depende fortemente da propagação de contexto para correlacionar rastreamentos entre diferentes serviços. Ao usar o AsyncLocalStorage, você pode garantir que o contexto de rastreamento seja propagado corretamente dentro de sua aplicação Node.js, permitindo que você construa um sistema de rastreamento distribuído abrangente.

Muitos SDKs do OpenTelemetry utilizam automaticamente o AsyncLocalStorage (ou cls-hooked se o AsyncLocalStorage não estiver disponível) para a propagação de contexto. Verifique a documentação do SDK OpenTelemetry escolhido para obter detalhes específicos.

Conclusão

O AsyncLocalStorage é uma ferramenta valiosa para gerenciar a propagação de contexto assíncrono em aplicações JavaScript do lado do servidor. Ao usá-lo para rastreamento de requisições, autenticação, logging e outros casos de uso, você pode construir aplicações mais robustas, observáveis e fáceis de manter. Embora existam alternativas como cls-hooked e Async Hooks, o AsyncLocalStorage é geralmente a escolha preferida devido à sua natureza nativa, desempenho e facilidade de uso. Lembre-se de seguir as melhores práticas e estar ciente de suas limitações para aproveitar suas capacidades de forma eficaz. A capacidade de rastrear requisições e correlacionar eventos através de operações assíncronas é crucial para construir sistemas escaláveis e confiáveis, especialmente em arquiteturas de microsserviços e ambientes distribuídos complexos. O uso do AsyncLocalStorage ajuda a atingir esse objetivo, levando, em última análise, a uma melhor depuração, monitoramento de desempenho e saúde geral da aplicação.